Programming Style Guide
=======================

It is essential that your programs be human-readable. The Java compiler does not care how your code looks or if you have comments explaining tricky or unusual blocks of code. At some time, however, a human will be looking at your code. That person might be the TA marking your code, fellow workers that need to use or maintain your code, or even yourself when you look back at the code you have written. As such, your code must be easy to read.
 
In order to help us write readable code, we will use a coding convention for all programs that we write (for assignments) in this course. Style grades may be awarded as part of the grade for some questions/assignments. 

Style grades may appear as deductions for any question/assignment where Style marks are not specified.
 
Initial comment block: 
---------------------- 
Each .java file should begin with a comment block containing 
o) course name, assignment number, problem number
o) your name, your student ID number, date
o) brief description of the program (or class if it is not a program)
o) compilation instructions and usage instructions (if applicable)
o) examples (if applicable for a program)
 
Method comment blocks: 
----------------------
Each method (except main) should also have a leading comment block.  This comment block should contain
o) short description of the method
o) input parameters (type and order)
o) return type
o) contract
   - preconditions (restrictions on the input parameters)
   - postconditions (guaranteed output, if preconditions are met)
o) side effects (things the method does besides returning a value).
o) examples 
 
Simple "get" and "set" methods do not need comment blocks.  
Simple constructors do not need comment blocks.  
 
Appropriate names: 
-----------------
Variables, methods and classes should all have "good" names. 
A good name should convey the meaning (or intended use) of 
the given variable/method/class. For example, 
   use score instead of s, 
   use surname instead of x, or 
   use averageValue instead of y2. 

When the name involves more than one word, use CamelCase (printArrayInReverse()) or use underscores (print_array_in_reverse()).  Be consistent!

Class names must be capitalized (Student, Card, Player)

Variables and methods must be lower-case. For CamelCase names, the 
first word is not capitalized (numberOfCards, lastPlayer).

Matrices (arrays) can be capitalized to be consistent with 
mathematical conventions when using mathematics. For example, M is 
an acceptable name for a matrix.

Constants should be upper-case (PI, SPEED_OF_LIGHT) using underscores to separate words. Example, Integer.MAX_VALUE is a constant in the Integer class that says how large the largest int on your computer is.
  
note: Single letter constants are fine if they correspond to 
something that usually is represented by a single character. 
For example, C or c for the speed of light, and G for the gravitational constant are fine. 

Avoid abbreviations. Avoid using single character names. 
Using i, j, k for loop counters is fine though. Using x, y for coordinates is also fine. Use num instead of number is fine. For example, numBalls is acceptable (instead of numberOfBalls).
 

Proper indentation: 
------------------
Use of indentation is essential for readable code. The body of each block of code should be indented 
(within the { and } of that block). For example, the entire code in a class should be indented, the code in a for loop should be indented, etc. Nested blocks should be indented within each other. 

(DrJava, and most modern text editors, will help you indent your Java code properly. See http://www.drjava.org/docs/user/ch03.html for instructions with DrJava.)

If you used Python in 1005/1405, then you should already be familiar with good indentation.
 

Whitespace: 
----------
Adding blank lines between certain blocks of code will help improve the readability of the code. Adding too many blank lines, 
however, will reduce the readability of the code. 
 

Inline and Block Comments: 
-------------------------
Comments should be added to your code in places where needed. 
You should not add comments for simple-to-understand or intuitively obvious code. Comments should help the reader 
understand the code.  

Too little comments may prevent understanding what the code does.  
Too many comments may make the code difficult to read. 
 
 
The webpage of supplemental material for the Sedgewick and Wayne textbook (Programming in Java) has many code samples 
(http://introcs.cs.princeton.edu/java/code/). 

Use these as a partial guide for the coding style mentioned above. You will notice that there are very few inline comments in first few programs (as they are simply not needed). Note also that the initial comment block in these sample programs do not contain any 
identifying information, which we require for this course. 